 Acrobat file (312K) |
 ClarisWorks 4 file (71K) |
 not available yet |
| Technote 1041 | MARCH 1996 |
See the discussion of this topic in the corrections for Chapter 2.
See the discussion of this topic in the corrections for Chapter 2.
The following characteristics of Macintosh pathnames should be noted:
Add the following row to Table 2-10:
Working directory Directory ID Empty string the target object is the reference number or NIL directory specified by the directory ID in dirID
Replace the last sentence in the first paragraph with the following:
"When an application starts up, its default directory is set to the directory in which the application resides. Thereafter, the application can designate any directory as its default directory."
Change the field descriptions to:
drXTFlSize The size (in bytes) of the extents overflow file. drCTFlSize The size (in bytes) of the catalog file.
Replace the second and third paragraphs in the Map Nodes section with the following:
"A map node consists of a node descriptor and a single map record. The map record is a continuation of the map record contained in the header node and occupies 492 bytes (512 bytes in the node, less 14 bytes for the node descriptor, 2 bytes for each of the two record offsets at the end of the node, and rounded down to a multiple of a longword). (Note: The HFS file system's B*-tree manager reads the bitmap information a longword at a time.) A map node can therefore contain mapping information for an additional 3936 nodes.
If a B*-tree contains more than 5984 nodes (that is, 2048 + 3936, enough for around 25,000 files), the File Manager uses a second map node, the node number of which is stored in the ndFLink field of the node descriptor of the first map node. If more map nodes are required, each additional map node is similarly linked to the previous one."
Add the following bit definition to vcbAtrb for System 7.5 or later:
Bit Meaning 10 Set if the volume's blocks should not be cached (System 7.5 and later only). This allows access to RAM disk volumes to bypass the File Manager cache. It has the same affect as setting the noCache bit (bit 5 of ioPosMode) for all File Manager reads and writes to the volume. Non-block aligned requests may still be accessed through the cache.
Change the field descriptions to:
vcbXTAlBks The size (in allocation blocks) of the extents overflow file. vcbCTAlBks The size (in allocation blocks) of the catalog file.
For files, the bits in ioFlAttrib have the following meanings:
Bit Meaning 0 Set if file is locked. Can be changed with the PBHSetFLock or PBHRstFLock functions. 1 Reserved. 2 Set if resource fork is open. 3 Set if data fork is open. 4 Set if directory. (Always clear for files.) 5 Reserved. 6 Set if AppleShare server "copy-protects" the file. Set by the AppleShare foreign file system code when the server sets the CopyProtect bit returned by afpGetFileDirParms. 7 Set if file (either fork) is open.For directories, the bits in ioFlAttrib have the following meanings:
Bit Meaning 0 Set if the directory is locked. Can be changed with the PBHSetFLock or PBHRstFLock functions when volume is shared. 1 Reserved 2 Set if the directory is within a shared area of the directory hierarchy. 3 Set if the directory is a share point that is mounted by some user. 4 Set if directory. (Always set for directories.) 5 Set if the directory is a share point. Can be set or cleared by PBShare and PBUnshare. 6-7 Reserved
The VolMountInfoHeader data structure has been extended to include a flags word. The data structure is now defined as:
struct VolMountInfoHeader
{
short length; /* length of location data (including self) */
VolumeType media; /* type of media */
short flags; /* high-byte reserved for Apple, */
/* low-byte reserved for file system
specific use */
/* Variable length data follows */
};
In the flags word, bits 14 and 15 have been defined. All other bits in the
high-byte of the flags word should be left clear. Bits in the low-byte of the
flags word are file system specific. For, example, the AppleShare foreign file
system uses bit 0 to determine if server greeting messages should be shown or
suppressed.Bit 15 in the flags word tells the file system that accepts a VolumeMount request if user interaction can be performed. If Bit 15 is set, the file system must not perform user interaction. If Bit 15 is clear, the file system may perform user interaction through the mechanism supplied by the File System Manager (FSM).
Bit 14 in the flags word allows a file system to indicate to the caller of VolumeMount that although the VolumeMount request was successful, the VolMountInfo record passed needs to be updated. Programs should ensure bit 14 of the flags word is clear before calling VolumeMount and if bit 14 is returned set, the VolMountInfo record should be updated by calling PBGetVolMountInfoSize and PBGetVolMountInfo. If VolumeMount is unsuccessful, bit 14 in the flags word should be ignored.
Observant readers will note that the Alias Manager needs to use bits 14 and 15 in the flags word to interact with file systems when responding to a MatchAlias function call.
The PBRead and PBWrite functions give programs much more control over read and write operations than the high-level FSRead and FSWrite functions because PBRead and PBWrite allow access to the ioPosMode field.
Bits 0 and 1 of ioPosMode indicate where to start reading or writing data in the file. The values allowed in ioPosMode to set bits 0 and 1 are:
constant value description fsAtMark 0 ioPosOffset is ignored. Operation starts at current mark. fsFromStart 1 ioPosOffset is an offset from the beginning of file. fsFromLEOF 2 ioPosOffset is an offset from the logical end-of-file. fsFromMark 3 ioPosOffset is an offset from the current mark.Bits 4 and 5 of ioPosMode are cache usage hints passed on to the file system that handles requests to the volume the file is on. Bit 4 is a request that the data be cached (i.e., please cache this). Bit 5 is a request that the data not be cached (i.e., please do not cache this). Bits 4 and 5 are mutually exclusive - only one should be set at a time. However, if neither is set, then the program has indicated that it doesn't care if the data is cached or not. The values allowed in ioPosMode to set bits 4 and 5 are:
value description 0 I don't care if this request is cached or not cached. 16 Please, cache this request if possible. 32 Please, I'd rather you didn't cache this request.
The drvNum parameter, which specifies the volume, can be a drive number, volume reference number, 0 (the default volume), or a working directory number. The volName parameter must point to a Str27 buffer or must be set to NIL. The freeBytes parameter will not be accurate on volumes with over 2 GB of free space.
If the value of ioVolIndex is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way to determine the volume. However, because PBHGetVInfo returns the volume name in the buffer whose address you passed in ioNamePtr, your input pathname will be modified. If you don't want your input pathname modified, make a copy of it and pass the copy to PBHGetVInfo.
The volume name returned by PBHGetVInfo is not a full pathname to the volume because it does not contain a colon.
You can use the FSpGetFInfo function to obtain the Finder information about a file, but not a directory.
You can use the FSpSetFInfo function to set the Finder information about a file, but not a directory.
The FSpExchangeFiles function swaps the data in two files by changing the information in the volume's catalog and, if either of the files are open, in the file control blocks. Specifically, the following changes are made.
The following fields in the two files' volume catalog enteries are exchanged (as seen by PBGetCatInfo):
ioFlStBlk The first allocation block of the data fork ioFlLgLen The logical end-of-file of the data fork ioFlPyLen The physical end-of-file of the data fork ioFlRStBlk The first allocation block of the resource fork ioFlRLgLen The logical end-of-file of the resource fork ioFlRPyLen The physical end-of-file of the resource fork ioFlMdDat The date and time of the last modificationBoth the data and resource forks of the two files are exchanged.
The following fields in any open file control blocks to the two files are exchanged:
fcbFlNum The file ID number fcbDirID The file's parent directory ID fcbCName The file's name
If the HOpenDF or PBHOpenDF function fail with a paramErr result code (indicating that the HOpenDF or PBHOpenDF function is not available), you should retry your request passing the same parameters to HOpen or PBHOpen. For example:
error = HOpenDF(vRefNum, dirID, fileName, permission, &refNum); if ( error == paramErr ) /* HOpenDF not supported, so try HOpen */ error = HOpen(vRefNum, dirID, fileName, permission, &refNum);
The parameter blocks are missing the ioFVersNum field. ioFVersNum should be initialized to zero because these calls will fall through to the now-obsolete Macintosh File System (MFS) code if the volume accessed is an MFS volume.
The parameter blocks are missing the ioMisc field. ioMisc must be initialized to zero before calling PHHOpenDF, PHHOpenRF, or PBHOpen. Failure to initialize ioMisc to zero on some Macintosh models will cause the system to crash.
Change the description of PBGetCatInfo's ioFDirIndex usage rules to:
The PBGetCatInfo function selects a file or directory according to these rules:
The parameter block is missing the ioNamePtr field. ioNamePtr and ioVRefNum are both used to specify the volume.
The parameter blocks shows ioForeignPrivIDirID as a Integer when it is really a LongInt.
The File Manager, when the File Sharing or AppleShare file server is active, will execute requests in arbitrary order. That means that if there is a request that depends on the completion of a previous request, it is an error for your program to issue the second request until the completion of the first request. For example, issuing a write request and then issuing a read request for the same data isn't guaranteed to read back what was written unless the read request isn't made until after the write request completes.
Request order can also change if a call results in a disk switch dialog to bring an offline volume back online.
The offsets for the Volume Parameter Variant are off by 2 starting at ioVClpSiz because ioVAlBlkSiz is a long, not a word. So, the offset for ioVClpSiz should be 52, the offset for ioAlBlSt should be 56, etc.
Replace the two bullet points with the following three bullet points:
Pages 3-30 to 3-31 and 3-59 discuss activation of additional user interface elements in custom standard file dialogs. The parts of that discussion that refer to having multiple edit-text items omit mention that it is necessary for the activation procedure to call TECalText, set myTEHandle^^.crOnly to 1, and call TESetSelect to work properly, as in the code snippet below.
IF (activating) THEN
BEGIN
{Note DialogPeek not WindowPeek used}
dlgPeek := DialogPeek(theDialog);
{Access TEHandle shared in common by all the editText items in }
{the dialog. This field current at activate time.}
myTEHandle:= dlgPeek^.textH;
{Must redo lineStarts on activation}
TECalText(myTEHandle);
{Must set crOnly on activation}
myTEHandle^^.crOnly := 1;
{Ensure proper setting of selection}
myTECharLength := myTEHandle^^.teLength;
selectionLen := myTEHandle^^.selEnd - myTEHandle^^.selStart + 1;
If (myTECharLength > selectionLen) THEN
TESetSelect(0,myTECharLength,myTEHandle);
END;
The code listing does not set the sfScript field of the StandardFileReply record when returning the pseudo-item sfHookChangeSelection. This can cause Standard File to always set the selection to the last file in the directory. Adding the line:
myReplyPtr^.sfScript := smSystemScript;before the line:
MyDlgHook := sfHookChangeSelection;will fix the problem.
At the bottom of page 4-19, it is stated that ResolveAlias never updates a minimal alias. This is not true.
ResolveAlias calls MatchAlias to resolve the alias and if MatchAlias returns with needsUpdate set to true, then ResolveAlias updates the alias by calling UpdateAlias (which makes it a full alias) and returns with wasChanged set to true. If you require that minimal aliases stay minimal aliases, you can either call MatchAlias (which does not update aliases),or you can create a copy of the alias record with HandToHand, pass the copy of the alias record to ResolveAlias, and then dispose of the (possibly updated) copy of the alias record.
Just a typo... the title of this says it all.
Add this warning:
The existing application program interface to the Disk Initialization Package as described in Inside Macintosh: Files will continue to be supported by the enhanced Disk Initialization Package. Applications which wish to initialize only Macintosh disks will continue to work and will require no changes. However, if an application wants to initialize non-Macintosh disks, it must use the new extended DIXFormat and DIXZero calls.
Figure 5-1 The disk initialization dialog box
The disk initialization dialog box allows the user to name and specify the format of the new disk. The appearance of the disk initialization dialog box changes to reflect changing conditions. For example, the icon changes to show which drive contains the disk. The Format menu items change to show what disk formats can be used with the disk and disk drive combination. Also, the text of the dialog box changes according to what is wrong with the disk. The text might read "This disk's format cannot be read by this drive" if the Disk Initialization Manager detects that the disk drive cannot use a disk's format (for example, if a double-sided disk is inserted in a single-sided disk drive, or a high-density disk formatted using GCR instead of MFM is inserted in an Apple SuperDrive).
Regardless of the initial appearance of the disk initialization dialog box, it disappears if the user clicks Eject or Cancel. If, however, the user decides to initialize the disk, the text in the dialog box changes to warn the user that initialization erases any previous data on the disk, as illustrated in Figure 5-2.
Figure 5-2 The disk initialization warning
If the user selects continue, the Disk Initialization Manager attempts to initialize it. If an error occurs and the initialization fails, an alert box notifies the user, and the disk is ejected.
The extended Disk Initialization Manager also provides a mechanism for using the standard interface to reinitialize (reformat) disks that are already formatted. (This mechanism is useful, for example, when the user wants to reinitialize a disk with a different disk format.) The Finder takes advantage of this mechanism with its Erase Disk command, illustrated in Figure 5-3. After the user selects the erase operation from this dialog box, the reinitialization begins immediately, without further warnings. If desired, your application can use this same standard interface to allow users to reinitialize mounted disks (other than the startup volume). Your application can customize the text to be displayed in such a dialog box. Note that only a few utility applications actually need to provide users with this capability.
Figure 5-3 The Reformat dialog box
If you are writing a utility program such as a disk-copying application, you might wish to initialize new disks or reinitialize valid disks without displaying the standard disk initialization dialog box. For example, your application might allow users to initialize multiple disks without having to respond to the standard dialog box each time. The Disk Initialization Manager provides low-level routines that allow you to do so. Unless you are writing a utility program of this type, you don't need to use these routines.
Boolean HasExtendedDIFunctions(void)
{
long response;
if (Gestalt(gestaltFSAttr, &response) == noErr)
return ((response & (1L << gestaltHasExtendedDiskInit)) != 0);
else
return (false);
}
pascal OSErr DIXFormat(short drvNum, Boolean fmtFlag, unsigned long fmtArg, unsigned long *actSize); drvNum Contains the driver number of the drive to format. fmtFlag Contains a boolean value which specifies the meaning of the fmtArg paramter. fmtArg If fmtFlag is true, fmtArg specifies the actual value to be passed to the disk driver in the csParam field of the parameter block when the "format" _Control call is made to initialize the disk media. (The value is an index into the size list. For an explanation of appropriate values for this parameter, see the Technical Note "What Your Sony Drives For You".) If fmtFlag is false, fmtArg specifies the desired size of the media in number of 512-byte blocks. The disk driver is called to get possible sizes and the values in an to attempt to match the requested size. If more than one size list entry exists for the same size, the first entry in the list returned by the driver that best matches the fmtArg parameter will be used. For more information about the size list, see the Technical Note "What Your Sony Drives For You". If the specified size is larger than the largest size in the size list returned by the driver, then the largest size will be used and that size is returned in actSize. If the specified size is smaller than the smallest size in the size list returned by the driver, then the smallest size will be used and that size is returned in actSize. For a specified value that is in between and without an exact match, the value closest to and smaller than the requested size is used. actSize Contains a pointer to an unsigned long. Upon completion of a successful formatting operation, DIXFormat places the actual size of the formatted media in number of 512-byte blocks into the field referred to by this parameter.The formatting of file systems requiring specific media formats should be done by specifying those media formats explicitly and not by counting on disk size alone. Foreign file systems with specific media requirements should use the driver specific information in the size list or should make appropriate driver _Status calls for additional information when called upon to "evaluate the size list".
As in DIFormat, DIXFormat does not unmount the volume. You have to unmount the volume before issuing this call if necessary. If the volume has not been unmounted, then DIXFormat will return volOnLinErr error.
RESULT CODES
noErr 0 No error volOnLinErr -55 Volume is online lastDskErr -64 Last of the range of low-level disk errors firstDskErr -84 First of the range of low-level disk errors
pascal OSErr DIXZero(short drvNum, ConstStr255Param volName, short fsid, short mediaStatus, short volTypeSelector, unsigned long volSize, void *extendedInfoPtr); drvNum Contains the driver number of the drive to initialize. volName Contains a pointer to a Pascal string which specifies the name of the volume. fsid Contains the ID of the file system whose format should be written to the disk. The file system ID can be obtained using the File System Manager GetFSInfo function. mediaStatus Contains a flag to indicate the status of the disk media. Its value is the result code returned from the DIVerify function. If mediaStatus is non-zero, then the disk contains bad sectors and needs to be spared. If the file system specified doesn’t support bad block sparing, the Disk Initialization Package will just return this value as the function result. If the file system supports bad block sparing, then the Disk Initialization Package will gather the defect list and pass it to the file system. volTypeSelector Contains the volume type selector if the foreign file system supports more than one volume type. volSize Contains the size in 512-byte blocks of the file system that should be written to the drive specified by drvNum. This is the size returned in the actSize field by DIXFormat - the amount of space usable by a file system on the specified drive as it is currently formatted. If the specified size doesn't match with the current disk format size, DIXZero will return diCIVolSizeMismatchErr. fsParams Contains a pointer to the foreign file system’s extended formatting information, or nil.
You must check to ensure DIXZero supports bad block sparing before passing anything except noErr as the mediaStatus parameter. The following function, DIXZeroSupportsBadBlocks, shows how to make sure DIXZero supports bad block sparing.
Boolean DIXZeroSupportsBadBlocks(void)
{
enum
{
gestaltBugFixAttrsThree = 'bugx',
gestaltDIXZeroSupportsBadBlocks = 9
};
long response;
if (Gestalt(gestaltBugFixAttrsThree , &response) == noErr)
return ((response & (1L << gestaltDIXZeroSupportsBadBlocks)) !=
0);
else
return (false);
}
As in DIZero, DIXZero does not unmount the volume but it will, however, mount
the volume if the operation is successful. You have to unmount the volume
before issuing this call if necessary. If the volume is mounted when DIZero or
DIXZero is called, then a volOnLinErr error will be returned.RESULT CODES
noErr 0 No error diCIVolSizeMismatchErr 24 Specified volume size doesn't match with formatted disk size ioErr -36 I/O error paramErr -50 Drive number specified is bad volOnLinErr -55 Volume is already online nsDrvErr -56 No such drive lastDskErr -64 Last of the range of low-level disk errors … firstDskErr -84 First of the range of low-level disk errors memFullErr -108 Not enough memory
pascal OSErr DIReformat(short drvNum, short fsid, ConstStr255Param volName, ConstStr255Param msgText); drvNum Contains the driver number of the drive to format. fsid Contains the ID of the file system whose format should be written to the disk. The file system ID can be obtained using the File System Manager GetFSInfo function. (Use $0000 for the Macintosh HFS voluime format.) volName Contains a pointer to a Pascal string which specifies the name of the volume. msgText Contains a pointer to a Pascal string which specifies the explanatory text to be displayed in the disk initialization dialog box.In the past, reformatting disk was accomplished by calling the DIBadMount function with the high word of the evtMessage parameter set to noErr and the explanatory text was set with the ParamText function. The DIReformat function provides the caller the ability to provide the explanatory text, the default file system ID, and the default name for the reformatted disk.
noErr 0 No error diCINoMessageTextErr 28 msgText was not provided paramErr -50 Drive number specified is bad nsDrvErr -56 No such drive lastDskErr -64 Last of the range of low-level disk errors … firstDskErr -84 First of the range of low-level disk errors memFullErr -108 Not enough memory
Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help